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Cka|»t«r  1:  Overview 


1  Overview 

TEMPLATE:  Deicribe  what  this  library  does  here. 


1.1  Examples 


TEMPLATE:  Give  examples  here. 
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2  Functions 

The  foUowing  sections  describe  each  function  provided  by  libooverwatchmove,  including  the 
format  and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 

TEMPLATE:  Correct  argument  lists  and  descriptlmis  of  these  functions. 


2.1  uowm  unit 
void  uoeB_iait() 

uomuialt  initialises  libuoverwatchmove.  Call  this  before  any  other  libuoverwatchmove  func¬ 
tion. 


2.2  ttowmusUst unit 

void  nov.clnss.init(pareat.claes) 

CLASS.Pni  parent. clus; 

'parent.clasa* 

Clam  <rf  the  parent  (dedaied  edth  elaas.daclare.clasa) 

uoan.elass.init  creates  a  handle  for  attaching  noverwatchmove  class  information  to  vehicles. 
The  parant.class  will  Ukely  be  safobj.class. 


2.S  uowm.xrnnte 

void  ooan.eroato(vahiclo.id,  parans,  po.db,  etdb,  quad.data) 
int  v^cle.id: 

IPOni.PMUIIIXMZC.MTA  eparM; 

P0JPATAMA8I  upo.db; 

CIBI  ectdb; 

•gaad.data; 


QDAOJPATA 


4 


Libuoverwatchmove  Programmer’s  Guide 


Spedfiei  the  vehicle  ID 
*paraM*  Specifies  initial  parameter  values 

*po.db’  Specifies  the  PO  database 

*ctdb,  qaad.data* 

Specify  the  terrain  database 


uoiBLcreate  creates  the  uoverwatchmove  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
Mock  of  libdass  user  data. 


2.4  uowm.jdentroy 

void  uonB.dentroy(vehiclo_id) 
iat  vehicle.ld; 


‘vahlele.ld* 

Specifies  the  vehicle  ID 

iie«a.4ootx<7  frees  the  uoverwatchmove  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  claaa^ree.uner.data. 
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1  Overview 


Libapocepos  implemeiits  a  unit-level  Preparatory  task  for  Occupy  Position.  This  preparatory 
task  finds  covered  and/or  concealed  positions  along  the  battle  position  and  instructs  the  subordi¬ 
nates  to  go  toward  these  positions.  This  task  ends  when  the  subordinates  have  reached  the  desired 
podtions.  The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C 
using  the  ^ni2cli’  utility  (see  section  ‘Overview*  in  LibTask  Programmer’s  Manual). 

Four  parameters  are  passed  to  SN.UPrepOcpjPos:  left  TRP,  right  TRP,  engagement  area  TRP, 
and  battle  position.  Based  on  the  battle  position  and  the  number  of  subordinates,  the  number  of 
vehicles  per  segment  (the  battle  position  is  made  up  of  one  or  more  line  segments)  and  the  battle 
areas  (areas  where  *vb  vehicle  searches  for  cover)  are  calculated.  The  subordinates  are  ordered 
by  job  numbers,  and  are  assigned  positions  from  one  end  of  the  battle  position  to  the  other  end 
so  no  vehicle  crossover  occurs  while  they  are  travding  to  their  positions.  The  cover /concealment 
farthing  algoiitlun  uses  ctdb  utilities  which  can  tend  to  be  expensive,  especially  is  the  battle  areas 
are  large.  Therefore,  the  search  is  divided  ammig  several  ticks.  Once  the  positions  are  found,  they 
are  passed  to  vmove  for  each  vehicle.  The  state  machine  then  sits  and  waits  until  the  vehicles  are 
in  their  desired  positiems. 


1.1  Task  Parameters 

The  SILBPrepOcpyPos  task  has  four  parameters: 

typedef  struct  upoccpos.paraaeters 

i 

ObJectIO  engageaeat.area; 

ObjectIO  trp.riglit: 

Obj actio  txp.left; 

(ftJectXO  battla.positioa; 

>  OPOCCPOS.PAkilfEIEIIS; 

*sBgi^asmnt.araa* 

Spedfies  a  persistent  object  which  defines  the  engagement  area.  The  engagement  area 
is  a  point  object. 

*txp.jri^t* 

Specifies  a  persistent  object  which  defines  the  right  bound  of  the  sector  of  fire  for  the 
unit.  This  object  is  a  point  object. 
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‘txp.laft’ 

Spedfies  a  persistent  object  which  defines  the  left  bound  of  the  sector  of  fire  for  the 
unit.  This  object  is  a  point  object. 

‘batt le.poa it ion’ 

Specifies  a  persistent  object  which  defines  the  battle  position.  The  battle  position  is  a 
line  object. 


1.2  Parametric  Data 

There  are  deven  parametric  data  entries  for  SM.UPrepOcpjPos: 

aiB.allowable.Tiaibilit7  has  a  value  firom  0.0  to  1.0  and  specifies  the  minimum  visibility 
(0.0  bdng  not  visible  and  1.0  bdng  completdy  visible)  of  the  engagement  area  TRP  required  for  a 
pdnt  to  be  considered  a  good  cover  position 

tre«_opacit7  has  a  value  from  0.0  to  1.0  and  spedfies  the  degree  to  which  one  can  see  through 
tree  lines.  0.0  means  tree  lines  are  ignored,  and  1.0  means  that  tree  lines  completdy  block  the  path 
of  vidon 

front.dist.p«rcoatage  specifies  how  far  in  fhmt  of  the  battle  podtion  to  search  for  cover 
podtions.  The  value  specified  is  a  percentage  of  the  totd  battle  podtion  length. 

bnck.diat.p«rc«ntage  spedfies  how  far  back  from  the  battle  podtion  to  search  for  cover  po¬ 
dtions.  The  value  spedfied  is  a  percentage  of  the  totd  battle  podtion  length. 

f  ire.aector.overlap.pereentage  spedfies  the  degree  to  which  fire  sectors  overlap 

grldLspneing  spedfies  how  carefully  the  search  will  be  perfmmed.  A  low  vdue  specifies  a  quick 
search  (posdbly  ovetloddttg  some  good  cover  positions)  while  a  high  vdue  spedfies  a  search  that 
takes  longer  but  detects  more  cover  positions.  This  vdue  is  in  meters  and  spedfies  the  distance 
between  sample  points. 

eoarehee.per.tiek  spedfies  how  many  sample  points  for  each  vehide  will  be  processed  per 
tkk.  If  there  are  four  vehides  and  two  searches  per  tick,  then  dght  sample  pdnts  will  be  processed 
per  tick. 

■■r.building.eldth  is  used  to  ensure  that  a  conceded  pdnt  doesn’t  end  up  indde  a  building. 
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It  should  be  set  to  the  maximum  building  width  in  the  area  being  searched. 

bull^coverege  specifies  the  percentage  of  the  hull  that  is  protected  from  direct  fire  by  the 
ground.  It  is  a  number  between  0.0  and  1.0. 

eBgagem&t_area.siue  specifies  the  size  of  the  engagement  area.  It  is  expressed  in  percentage 
meters.  The  front  of  the  engagement  area  is  a  certain  distance  in  front  of  the  engagement  area 
TRP.  This  distance  is  a  percentage  of  the  distance  from  the  battle  position  to  the  engagement  area 
TRP.  •ngageaeat.area.size  specifies  this  percentage.  Anything  closer  to  the  battle  positior  than 
the  front  <rf  the  engagement  area  TRP  will  be  blocked  from  view  by  the  earth, 

apood  specifies  the  speed  (in  m/s)  at  which  ground  vehicles  will  move  to  their  positions 


C)u4>t«r  2:  Foncticms 
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2  Functions 


The  fcdlowing  sections  describe  each  function  provided  by  libupoccpos,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  upoccposJnit 
void  iqpoccpoe.inltO 

i^ccpos.lnit  initializes  libupoccpos.  Call  this  before  any  other  libupoccpos  iimction. 


2.2  upoccpos_clatsJinit 

void  190eep00.claM.init  (parent  .class) 

CLASS.Pni  parent. class; 

*pareBt.claes* 

Glass  of  the  parent  (dedaied  vrith  claM.declare.elass) 

190ccpos.claM.inlt  creates  a  handle  for  attaching  upoccpos  class  inferipation  to  vehicles. 
The  parent.clMS  vdQ  lihdy  be  safobj.clMo. 


2.S  upoccpos^rente 


void  i9oe^oe.ereate(veldcle.id,  paraas,  po.db,  ctdb) 
iatS2  vehicle.id; 

IIPOOCPOS.PABAIIETUC.DATA  eparaeM; 

P0.0dTIBASB  opo.db; 

cm  eetdb; 


*vehiele.id* 

Specifies  the  vehicle  ID 

^panas*  Spedfies  initial  parameter  values 

i.db*  Specifies  the  PO  database  where  the  task  can  be  found 
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‘etdb*  Specifies  the  terrain  database  currently  in  use 


tqpoeepos.create  creates  the  upoccpos  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  upoccpos-destroy 

void  iqtocepoe.deetroyCvehicle.id) 
iat  eehiele.id; 


*vehicle.id* 

Spedfies  the  vehicle  ID 


iqpocepoa.deetroj  frees  the  upoccpos  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  claas.free.UBer.data. 


2.5  upoccposJnitJtaskjitate 


void  npoc^oa.init.taBk.state(task.  state) 
TaskClass  *task; 

TaakStateClass  estate; 


*task'  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

'stats’  Returns  the  initialized  state 

Given  a  aew  SILQPr^O^jPos  task  that  is  about  to  be  created,  i9oc^os.iait.task.state 
initialiies  the  modd  use,  and  state  variables. 
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S.l  Cover  Algorithm 

of  finding  the  cover  positions  in  one  tick,  the  search  is  distributed  among  several 
until  good  cover  positions  are  found.  Each  vehicle  is  pven  an  area  about  the  battle  positiv 
which  to  search,  which  will  be  referred  to  as  the  ’battle  area’.  Also,  a  default  position  along 
battle  front  (which  the  vehicle  will  use  as  its  destinatimx  point  if  no  cover  or  concealment  is  found) 
is  ealcnlated  for  each  vehicle.  For  each  vehicle,  three  ’lines’  consisting  of  equally  spaced  points  are 
eooatructed:  cme  along  the  left  dde  of  the  battle  area,  <ae  along  the  back,  and  one  along  the  right 
side.  During  each  tick,  a  few  of  these  points  are  used  as  "starting  points"  or  "sample  pmnts"  in  the 
search  frw  cover  positkms.  For  each  sample  p<unt,  a  profile  array  (3-dimensional)  which  contains 
the  elevation  ci  the  ground  along  a  vectm  from  the  sample  point  to  the  engagement  area  TRP  is 
generated.  Any  two  consecutive  entries  in  this  array  define  tee  endpmnts  of  a  segment  along  the 
profile  with  a  oonstaat  slope. 


Then,  starting  with  the  segment  closest  to  the  engagement  area  TRP,  and 
last  segment  (ending  at  the  samide  pdnt),  the  following  occurs: 


progresring  to  the 


1)  The  naatiw  elope  of  the  line  fron  the  engagen 
point  of  the  aegnent  cloeeet  to  the  estgagesMut 
trade  of.  Thla  la  the  line  of  al^t  of  the  en< 
the  *tengent  vector.*) 


area  IIP  to  the 
n  TRP  Is  kept 
(also  known  as 


2)  Tko  line  supwnts  are  generated,  each  starting  fron  one  end  of  the 
current  profile  segsent.  These  line  se^ents  are  perpendicular  to 
the  ground  at  the  current  profile  sepMnt  and  have  a  length  that 
Is  equal  to  the  body  height  of  the  vehicle  that  Is  searching  for 
cover.  The  line  segneot  closest  to  the  sanple  point  will  be 
referred  to  as  *testllne  1*.  and  that  closest  to  the  engagssMnt 
area  TIP  as  *testllne  2* . 

3)  If  tile  tangent  vector  does  not  Intersect  with  testllne  1  but  does 
Intersect  with  testllne  2,  than  there  Is  a  hall  defilade  position 
ssawnhers  along  that  profile  segpMnt.  The  enact  point  Is 
calculated  by  detemlnlng  the  Intersection  of  the  line  tiwse 
en^olsts  are  the  t^  ends  of  the  testllnes  (points  A  and  B  on 
the  dlagran)  with  the  tangent  vector,  then  projecting  onto  the 


fbr  esdi  veUde,  the  covered  positions  with  the  mildest  slope  is  used  as  the  destination  point. 
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In  the  following  diagram,  a  hull  defilade  position  is  found  to  be  somewhere  on  segment  n^l. 

•ngagesient 


teatline  2  tangent  vector  area  TUP 

I  I  I 

B  I  I  I 

.  <-  I  I 

V  V 

— - - . - . - E 


A 


•  e  e  • 

->  .  ...  I 

I  ....  so^aont  n'^1 

I 

testliae  1 


I 

I 

segnent  n 


S.3  Concealment  Algorithm 

Concealed  points  are  only  searched  for  if  no  cover  pmnts  axe  fonnd.  ctdbAnd.gronndJntersecti(»() 
is  wed  to  determine  if  there  is  a  treeline  or  boilding  alcmg  certain  segments  ti  the  profile  array,  li 
so,  the  location  is  marind  as  a  concealed  position. 

Not  aU  parts  of  all  segments  are  searched  for  concealment.  Only  the  portions  of  segments  that 
are  them  (higlMr  in  altitude)  the  tangent  line  are  searched,  since  intervinbility  would  foil  for  any 
portion  of  terrain  bdow  the  tangent  line.  Therefoe,  segments  that  have  the  tangent  line  pass  above 
them  are  not  checked  at  all  for  concealed  potitions. 

The  concealed  petitions  that  are  closest  to  the  vehicles’  defoult  locations  on  the  battle  position 
are  used  as  the  destination  points.  Concealed  positions  are  rally  used  if  no  cover  positions  are 
found. 


Ckaptar  4:  Dcbigging 
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4  Debugging 


WImb  debugging  for  Prep  Occnpy  Position  is  enabled  for  any  velucle(8)  (via  Veh  X  debug 
npoccpos  on’),  three  different  colors  of  TRP-style  points  are  pot  in  each  vehicle’s  overlay:  yellow, 
red,  and  green. 

The  yellow  points  represent  the  sa^le  points  (see  the  Algoritbns 
section)  for  a  given  vehicle. 

The  red  points  represent  the  cover  positions  found. 

The  green  points  represent  the  concealed  positions  found. 
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1  Overview 


Libnitb  implainenU  a  nnit-levd  task  which  controls  a  group  (currently  only  one)  of  vehicles 
returaiag  to  a  base  and  landing.  The  task  state  machine  is  written  using  the  AAFSM  format  which 
is  translated  to  C  using  the  *fn2ch*  utility  (see  section  ‘Overview’  in  LibTask  Progranuner’s 
Manual). 

liburtb  depends  on  libvtakeoff,  libvflwrte,  libvland,  libpo,  libvtab,  libclass,  libetdb,  libaccess, 
libteaiter,  and  libparmgr. 


1.1  Task  Parameters 


When  a  Slf.URTB  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  t^k  data 
stmetme  are  referenced.  The  parametos  are  represented  in  the  task  data  structure  as  follows: 


tjpedof  struct  «xtb.paraBeter8 

ObjeetIO  base; 
alM16  padding; 
floated  speed; 
floated  altitude; 

}  QUB^MUUBRRS; 


-  *base*  Spedfiea  the  base  for  the  vehicle  to  return  to.  This  base  can  be  a  point  object,  line 
object,  or  a  text  object. 

*apesd*  Spedfiee  the  speed  of  the  vehicle. 

'altitude* 

Specifies  the  altitude  of  the  velude. 


Cka#t«r  2:  Faaetkms 


3 


2  Functions 

The  foUowing  wctioiu  describe  eech  function  provided  by  liburtb,  including  the  format  and 
oi  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  urtbJnit 

void  urtb.initC) 

urtb.iait  initialises  liburtb.  Call  this  befme  any  other  liburtb  function. 


2.3  urtb.xlassJnit 

void  nrtb.elnBe.init<parent.clasa) 

CLASS.Pn  parent. class  i 

*pareiit.elsss* 

dais  ai  the  parent  (declared  with  class.deelaro.class) 

iirtb.class.init  creates  a  handle  for  attaching  nrtb  cUh  information  to  vehicles.  The  parent,  class 
wfll  Blnly  be  safobj.class. 


2.S  urtb^rente 

void  vrtb.eroatoCvekicle.id,  parans.  po.db,  ctdb) 
iBt32  veldcle.id: 

UKlB.PABtfBlBICJ>ATA  eparaas; 

POJMtTABASI  epo.db; 

CTDB  ectdb; 

*v«hiele.id* 

Spedftss  the  vdiicle  ID 

Eparaas*  Spediss  initial  paranwter  values 

*fojSb*  Specifies  the  PO  database  where  the  task  can  be  found 
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*ctdb*  Spedfiet  the  terrain  database  currently  in  use 

nrtb.ereate  creates  the  urtb  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block  of 
libdass  user  data. 


2.4  urtb^estroy 

void  urtb.dontroyCvehicle.id) 

Int  vehlclo.id; 

^•hiclo.id* 

Spediies  the  vehicle  ID 

urtb.dMtrpy  frees  the  nrtb  class  information  for  a  vehicle.  This  should  be  called  before  freeing 
the  class  user  data  with  claaa_f ree.user.data. 


2.5  urtb Jiiitjtatk.jitate 

void  iirtb.iBit.taak.atate(task,  atate) 

TankClnse  etaak; 

TaahStateClaaa  eatata; 

•task*  Spedfies  a  pointer  to  the  task  class  object  to  be  initialised. 

*state*  Hetums  the  initialized  state 

Given  a  new  SIL0B3B  task  that  is  about  to  be  created,  ttrtb_iait.taak_stato  initializes  the 
model  siae,  and  atate  variables. 
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1  Overview 


Libtttergeter  implements  a  unit  level  task  that  gets  a  list  of  all  capable  vehicles  in  that  unit.  If 
the  fire  technique  is  alternating  then  the  capable  vehicles  will  get  paired  up  before  giving  vtargeter 
the  appropriate  targeting  information.  The  task  state  machine  is  written  using  the  AAFSM  format 
which  is  translated  to  C  using  the  ‘fea2ch’  utility  (see  section  ‘Overview*  in  LibTask  Programmer’s 
Manual). 

During  targeting  operations,  there  are  two  states  as  described  below 

‘•tart’  When  in  this  state,  the  task  gets  the  number  of  capable  vehicles  and  spawns  the  vehicle 
targeting  task  libvtargeter.  If  the  fire  technique  is  set  to  alternating  then  the  vehicles 
are  paired  up  befisre  spawning  the  vehicle  targeting  task. 

‘■onltorlag* 

When  in  tUs  state,  the  task  gets  the  number  of  capable  vehicles  and  spawns  the  vehicle 
taigetiitg  task  libvtargeter.  If  the  fire  technique  is  set  to  alternating  then  the  vehicles 
are  paired  up  befine  spawning  the  vehicle  targeting  task. 

The  types  td  recommendations  made  by  this  task  during  either  state  can  be  controlled  by  the 
parametric  data  for  this  unit  subclass,  as  described  bdow. 


1.1  Parametric  Data 

Hie  format  of  the  parametric  data  for  this  unit  subclass  is  as  follows: 


(SILVTacgeter  (flrli|g.panse  cinteger  ailIiBeconds>» 


The  f  lriag..paue  derignates  the  amount  of  time  after  the  coordinated  vehicle  fires  before  the 
paired  vddde  caa  fire.  This  is  passed  to  vtargetm. 


1.3  Task  Parameters 

UbUtaifrtar  uses  task  parameters  only  when  configured  for  ground.  The  parameters  ared 
daecribed  hgr  the  foiknring  structures. 
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t7p«d«f  *1101  Ttarg«t«r.fire.p«XBlaaion 

< 

VTARSBTBR.IIEAPOIS.HOLD  -  1, 
VTAXGErEILHBAPOIS.FREE  -  2. 
VTAlUiETER.IIBAPOIS.TIGBT  -  3. 

>  VTA11GETER.FI1IE.PERMISSI0I; 


t]ip«d«f  amai  Vtarg«t«r.fire.t«cbniqu« 

i 

VTAItGETER.FIBB.TECHIiqUE.SIKULTilEOUS  »  1. 
VTAllfiEIER.nRE.TECHIiqaE.ALTEIUIATIIG  -  2. 
>  VTAR6STBR.FIRB.llCraiqOE; 


typadaf  struct  utargstsr.psmstsrs 

i 


> 


ObjsctID  vsctr.rgt.bttdCDlITOIlG.IUX_BREADTQ ; 

ObjsetID  vsctr.lft.bndCDHITORG.IUX.BREma ; 

VTAB6BTER_FIBE.PERMISSIQI  pszBission; 
VTAB6BIBR.FIBE.TECmiqaE  Ttsrg.firs.tschai<ius: 

VASSBSS.IfOOB  ▼sss.Bods; 

float32  rang#; 


flo«tS2 

iat32 

VASSBSS.FIBB.TTPE 
OTABflSmLPABAIIETraS : 


fira.at.posC2] ; 
BnB.point.sats ; 
fira.tppa; 


r8Ctr.xgt.bDd 

r8ctr.lft.bad 

paxBlccloa  spadfies  whether  the  vehicle  cannot  fixe,  can  fire  at  will,  or  can  only  fire  when  fired 
upon. 

rtazg.f  Ira.tactaniqna  specifies  whether  the  vehicle  can  fire  when  it  wants,  or  should  wut  to 
fire  after  another  vehicle  fires  (f<»  alternating  fire). 

rassowda  specifies  the  method  used  to  determine  targets.  The  three  modes  are  "Closest  to 
Sdf ,  "Sector  Points",  and  "Closest  to  Location". 

range  specifies  the  maximum  distance  that  the  vehicle  can  shoot. 


f  ira.at.po8  is  the  target  location. 
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iiiaL.poiiit.seta  is  not  used. 

fire. type  spediies  the  method  of  firing  at  the  enemy.  The  three  types  are  "Distributed  Fire", 
"Volley  Fire",  and  "None". 
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3  Functioni 


Tlie  fbUowmg  aectioni  describe  eech  function  provided  by  libutargeter,  including  the  format  and 
imtaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  utargJnit 

void  ««arg.iiiit() 

«taxg.iiiit  initialises  libutargeter.  Call  this  before  any  other  libutargeter  function. 


3.3  utarg.jclansJnit 

void  iitasg.elnM.lBit  (parent. clans) 

CUas.PTll  pareat.elaasi 

*parent.claM* 

daas  of  the  patent  (dcdared  with  claM.declare.clasa) 

vtasg.elass.lait  creates  a  haadk  fer  attaching  ntargeter  class  information  to  vehicles.  The 
paseBt.claM  is  om  created  with  classjdeclaiejclast. 


2.3  utargjcreatc 

void  vtasg.create(Telilcle.ld,  pasaas,  po.db) 
lat  vehicle.id; 

IITAIflRn.PAlUIIEnXC.Dm  •paraas; 

POJUTABASB  •po.db; 

*eahiele.ld* 

Spedfias  the  vehicle  ID 

*psTaas*  Spedto  initial  parameter  valoes 

*pe.db*  Spedfias  a  PO  database  where  task  objects  can  be  located 
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itt«zs.crMt«  CTMtee  the  utergeter  dais  infonnation  for  a  vehide  and  attaches  it  vehide’s  block 
of  Bbdaas  uier  data. 


3.4  utargudeatroy 

▼old  utarg.dastroy(Tahlcla.id) 
iat  Talilclo.id: 

Hrohicla.ld* 

Specifies  the  vehide  ID 

tttaxg.deetr0y  frees  the  utaigeter  class  infrvmation  for  a  vehide.  This  should  be  called  before 
fraeiag  the  class  user  data  with  elass.free.ttaer.data. 


3.5  tttargJiiitjkask..stata 


void  «targ.ialt.task.state<task»  state) 
TashClase  etaak; 

TaShStateClaBs  estate: 


*task*  Spedfies  a  poiater  to  the  task  class  object  to  be  initialised. 
*staeo*  Batnnu  the  initialised  state 


CBvea  a  new  SILVtargotor  task  that  is  about  to  be  created,  tttarg.init.task.state  initializes 
the  model  aad  state  variables. 
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1  Overview 


TIm  aait  travdiag  fibnry  provides  e  method  for  tasking  a  unit  of  vehicles  to  move  along  a  route. 
Tbe  route  is  specified  vin  a  PointClaae,  TextClase,  or  LineClaae  PO  object.  If  the  unit  is  larger 
than  one  vehicle,  the  vehicles  in  the  unit  will  be  kept  in  formation  by  increasing  or  decreasing  their 
command  speeds  periodically. 

TUs  fibraty  should  eventually  handle  arbitrarily  sized  units  in  a  hierarchical  manner.  At  this 
time,  it  will  try  to  control  all  the  vehicles  in  the  specified  unit  directly. 


1.1  Parnmetera 


ObJeetIO 

routej 

floae64 

apMd; 

floatM 

apeed.liait; 

ttiacfi 

foxBatienO ; 

UiBtS 

f  on.  type; 

ulntS 

readnarch; 

nines 

eonfozB; 

*ront«*  The  route  is  a  LineClaae,  Pointdaaa,  or  TextClaaa  PO.  It  provides  the  general  r/'  .te 

that  the  unit  wiD  follow. 

*apeed*  The  qpeed  defines  the  speed  of  the  unit,  tf  there  is  <mly  one  vehicle  in  the  unit,  it  will 
trasdi  at  exactly  thb  speed,  there  is  more  than  me,  the  speed  is  used  to  compute 
the  speed  of  the  individual  vdiides  to  keep  them  in  fonnatk». 

*apeed.liMt* 

This  somewhat  poody  named  parameter  defines  the  twMrtmwin  q)«ed  that  the  vdiicles 
may  travuL  It  should  be  zero  if  no  speed  limit  is  desired,  or  some  number  higher  than 
the  speed  parameter.  If  defined,  this  will  be  the  speed  used  as  the  catch-up  speed. 

*fenatlea* 

A  dmmcter  string  defining  a  formation  name  undostood  by  libf oxnatlondb. 
*fecn.,type* 

Another  poixfy  named  parameter.  Either  open  (0)  or  closed  (1).  This  is  currently  only 
used  for  roadmarch  spacing.  The  distances  meant  by  open  and  closed  is  defined  in  the 
parametric  data  as  ppen.apaciag  and  closod.spacing. 

*roadnarch* 

A  boolean  value  that  determines  whether  roads  will  be  used  in  the  route  or  if  formations 
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will  proceed  along  the  sides  of  the  road.  If  1,  the  vehicles  will  get  on  the  road  and  travel 
in  a  column  in  roadmaich  order. 

*emtwm’  A  bodean  value  that  determines  whether  the  input  route  will  be  conformed  to  the 
terrain.  In  the  future,  this  wiU  be  a  multi-value  parameter  that  determines  whether  to 
foDow  valleys  or  ridgelines  or  to  not  conform. 


1.2  Algorithm 

When  utraveling  is  spawned,  its  input  route  object  undergoes  some  initial  massa^ng.  First,  if 
the  ronte  is  a  single  point,  it  is  turned  into  a  two-point  route  starting  at  the  unit  location.  Next, 
if  the  ronte  is  to  be  cmiformed  to  the  terrain,  a  routine  in  libroute  is  called  to  change  the  route. 
This  currently  doesn’t  work  particularly  well.  Finally  (not  implemented  yet)  Icmg  sections  of  ronte 
wSl  be  broken  into  shorter  pieces. 

All  intonal  ronte  stmctnres  are  maintained  in  the  llbronte  format  defined  in  stdroute.h. 
The  ronte  is  stored  in  sections  composed  of  cross-conntry  and  road  segments.  If  the  roadmarch 
ittpnt  parameter  is  tnmed  on,  vehicles  will  drive  in  an  mder  defined  by  libfonationdb  on  any 
road  sectkms  in  the  input  unit  ronte. 

For  cross-conntry  sectkms,  libntravding  calls  libf oxantiondb  to  split  the  nnit  ronte  into  indi- 
vidnal  vehide  lontes.  These  rentes  will  have  vertices  offset  from  the  nnit  ronte  vertices  based  on 
the  input  fionnatian  parameter. 

A  tontiM  is  then  called  that  takes  the  list  of  subordinate  vehicles  and  the  individual  vehicle 
routas,  and  determines  a  snbaectimis  of  these  rmites  (somewhat  longer  than  500  meters).  Arrival 
ttmes  to  the  end  of  each  subsection  are  computed,  and  ^ipropriate  speeds  for  each  vehicle  are 
daterndnad  basad  on  the  input  unit  speed  and  the  distance  each  vehicle  wiU  need  to  travel  to  arrive 
at  the  sB^oint  of  the  snbsection  at  the  same  time  as  the  other  vehicles  arrive  at  th«r  endpoints. 

indhridnal  veldcla  mow  tasks  are  then  spawned,  and  pven  appropriate  parameters.  In  a  some¬ 
what  atomic  oparatioii,  the  vdiide  routes  are  tnmed  into  LinaClaaa  objects,  which  are  nsed  as 
iai^t  object  rafiaraices.  The  state  of  each  mow  tadc  is  then  monitored.  In  the  amplest  case,  when 
aB  mow  tasks  report  thqr  are  in  arrived  state,  the  ntravaling  task  cleans  up  and  goes  to  BID 
state. 

Typically,  the  ronte  is  somewhat  longer  than  the  snbronte  passed  to  the  individual  mow  tasks, 
and  the  vehklas  do  not  bdave  at  aU  as  expected.  Thus,  much  of  ntravaling  is  devoted  to  handUng 
s^  excq»tk»  conditions  and  idioqmcrades  of  the  mow  and  ■ovasi^  Ubraries. 
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Oa«  of  tbe  ftnt  things  thnt  needs  to  be  dealt  with  is  the  length  of  routa.  Rx>ad  segments  and 
t«Rnin>OQalbraMd  route  sections  may  cause  the  massaged  vehicle  routes  to  be  significantly  longer 
thin  can  be  stored  in  a  LlneClase  object.  To  get  around  this,  utraveling  breaks  the  long  unit 
route  into  shmrt  sections.  This  was  also  done  so  that  uoveoap  could  be  given  reasonably  short 
routes.  This  is  important  so  that  when  Boveui^  computes  a  speed  at  which  to  travel,  it  will  be 
reasonable  enough  to  keep  the  unit  roughly  in  formation. 

When  each  vehicle  gets  within  500  meters  the  end  of  its  subroute,  its  vnove  goes  to  arriving 
state.  When  all  the  vehicles  are  in  this  state,  utraveling  computes  a  new  set  of  subroutes,  new 
arrival  times,  and  passes  these  as  parameters  to  the  vuovea. 

SSaoe  things  always  happen  to  cause  the  vehicles  to  get  out  of  sync,  utraveling  will  periodically 
(currently  every  10  seconds)  recompute  the  arrival  times  and  update  the  vnoves.  This  helps  keep 
the  fumations  conect. 
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2  Functions 

The  foUowmg  sections  describe  each  function  provided  by  libutraveling,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 


2.1  utravJnit 

void  utrav.iaitCrouteBap) 

ROQTENiP.PTR  routeup: 

‘roataMp* 

Spedfiet  «  map  to  use  for  planning  around  rivers,  canopies,  etc. 

QtraT.lnlt  initializes  libutravding.  Call  this  before  any  other  libutraveling  function. 


2.2  utravuclassJnit 

void  utraT.class.initCpareat.class) 

CLASS..PTII  parent.class; 

*pareBt.clas8* 

Class  of  the  parent  (declared  with  class.declare.class) 

ntrar.clasa.init  creates  a  handle  for  attaching  utraveling  class  information  to  vehicles.  The 
pareat.elaas  will  likely  be  aafobj  .class. 


2.S  utravjcreate 


▼old  vtrae.createCTdhicle.id,  parasw,  po.db.  ctdb,  quad.data) 
iat  vehicle.id; 

Ummil6.PAlUIIEIRIC.DATA  eparau; 

PO.DATABASE  epo.db; 

CTD6  *ctdb; 
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QUAD.DATA  *quad_data: 

Mrahlela.id’ 

Spedfies  the  vehicle  ID 

‘puTMM’  Spedfiei  initial  parameter  values 

‘po.db*  Spedfies  the  PO  database 

*ctdb’  Pointer  to  the  CTDB  terrain  database 
*qaad.data' 

Pointer  to  the  quadtree  feature  database 

utrav.create  creates  the  utraveling  dass  information  fm  a  vehide  and  attaches  it  vehide’s 
block  of  libdass  user  data. 


2.4  utrav^estroy 

void  ntrav.dantxoyCTehiele.id) 
iat  vehlele.id; 

*Tdliiel«.id’ 

Specifies  the  vehide  ID 

vtrav.destzoj  frees  the  utravding  dass  information  for  a  vehide.  This  should  be  called  before 
fredag  the  dass  user  data  uith  claaa^ree.user.data. 
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1  O  vervie w 


Libvis8«68  implements  a  vehicle  level  task  which  identifies  the  most  urgent  target  and  makes 
recommendations  for  w^pons  to  use  against  that  target.  The  task  takes  its  primary  input  from 
the  libspotter  task  which  provides  lists  of  IFF  identified  vehicles  detected  by  available  sensors.  The 
task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the  8m2ch’ 
utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 

This  diagram  g^ves  an  overall  description  of  how  VAssess  chooses  a  new  target. 


I  spotted  list  of  eneiqr  vehicles  I 

4............................... — ..... — 4. 


I 

I 

I 

\  / 

..........................................4 

i  If  the  type  of  fire  is  DISTRIBUTED,  theni 
I  only  consider  vehicles  that  are  I 

I  «IQT*  being  targeted  by  soseone  else.  I 
I  If  *ALL*  spotted  vehicles  are  I 

I  being  targeted,  then  consider  all  I 

I  of  then.  ) 

4— — — - — — - .... - - — 4 


I 

I 

I 

\  / 


4->->— - — - ...... — - 4 

I  Only  consider  vehicles  of  the  highest  I 
I  priority.  I 

4-.- - 4 

I 

I 

I 

\  / 

4....... - 4 


I  Choose  the  vehicle  that  is  the  closest.  I 
4— .......................................4 


The  f<»mat  of  the  parametric  data  is  as  follows: 


(SILVAesoss  (background  [on  I  off]) 
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(saimora  <naM>  <iiam«>  ...) 

(veapona  (<vehicle-claaa-Bask>  <vehicle-cla88'Viilue> 

(<Bin  range>  <aaz  raiige>  <naBa>  <aiunition>) 

(<min  raiige>  <Baz  range>  <naBe>  <iiiunition>) 

...) 

(<vahicl«-class> 

(<Bin  rang«>  <max  rang«>  <naiBe>  <iinmition>) 

(<min  range>  <8uuc  range>  <naBe>  <anmition>) 

...) 

...) 

(looking.tick.period  <integar  ■sec>) 
(r««Taluating_tlck_period  <integar  ■>•€>) 
(r«coaMiidatlon.paraiatanc«_tiM  <intagar  naac) 
(aaaaaaaant.type  Cair  (  ground]) 

(ranga.factor  <raal>) 

(aapact .factor  <raal>) 

(paraiatanea.factor  <real>) 

(■obilit7.and.flra_factor  <raal>) 

(fira.f actor  <raal>) 

(■ax.liita.on.targat  <lntagar>) 

(targat.priorit lea . 

((<priorlty>  <vahlcla»claaa>naak>  <vahicla-claaa-valua>) 
«  «  • 

(<priorit7>  <vahlcla>claaa>maak>  <vahicla'claaa>valua>) 


The  background  parameter  specifies  whether  the  task  should  automatically  be  included  in  the 
background  task  frame  of  this  vehicle.  Normally,  this  will  have  the  value  on  to  indicate  it  should 
be  included. 


The  sensors  parameter  contains  the  names  sensors  which  may  be  manipulated  during  the 
assessment  process.  Currently  no  sensors  are  manipulated. 


The  wmtfoam  parameter  contuns  the  list  of  data  used  to  provide  weapon  and  munition  recom¬ 
mendation  agbinst  threats.  <vehlcle~class-Biask>  is  a  bitwise  OR  combination  of  SIMNET  object 
type  mask  fields  which  will  be  checked  for  a  match  agidnst  the  values  encoded  in  the  <vehicle- 
claa8>value>.  <veliiclo*’class-value>  is  a  bitwise  OR  combination  of  SIMNET  object  type 
value  fidds  which  are  used  to  match  against  the  assumed  object  type  of  the  threat.  If  the  fields 
match,  the  first  weapon  nano  and  nunition  for  which  the  threat  falls  within  the  nln  and  naz 
ranges  will  be  chosen  as  the  weapon  and  muniti<m  recommendation. 


Hie  lookiag.tick.period  parameter  specifies  how  often  the  task  should  process  input  when 
BO  targets  are  detected. 
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The  rm^wmiumting  tlelt  parlod  parameter  specifies  how  often  the  task  should  process  input 
when  a  target  is  ctirrently  recommended. 

The  recomMndation_persiatence.tiae  parameter  specifies  the  amount  of  time  that  a  chosen 
threat  should  remain  chosen  even  after  is  becomes  undetected  by  all  available  sensors. 

The  assesnent.type  specifies  the  type  of  algorithm  used  to  determine  threat.  Currently,  the 
only  two  types  supported  are  are  air  and  ground. 

The  range.factor  parameter  specifies  a  multiplier  from  0.0  to  1.0  rating  range  as  a  criteria  for 
threat  with  respect  to  other  criteria.  Currently,  range  is  the  only  criteria  used  to  classify  threat. 


The  aspect.faetor  specifies  a  multiplier  from  0.0  to  1.0  rating  aspect  angle  as  a  criteria  for 
threat  with  respect  to  other  criteria.  Currently,  only  assessment_type  air  uses  this  criteria. 

The  persieteace.f  actor  parameter  specifies  a  multiplier  by  which  an  already  chosen  threat 
will  be  evaluated.  For  instance,  a  factor  of  2.0  means  that  once  a  target  is  chosen,  other  targets 
will  not  be  chosen  unless  they  become  less  than  half  the  distance  to  the  vehicle  than  the  chosen 
threat  (assuming  range  is  the  only  criteria). 

The  ■obility.and.flre.faetor  specifies  a  multiplier  from  0.0  to  1.0  rating  the  appearance 
of  both  a  mobility  kill  and  firepower  kill  for  threat  with  respect  to  other  criteria.  Currently  only 
as8e8smeat.type  ground  uses  this  criteria. 

The  fire.f  actor  specifies  a  multiplier  from  0.0  to  1.0  rating  the  appearance  of  just  a  firepower 
kin  for  threat  with  respect  to  other  criteria.  Currently  only  assessmentjtype  ground  uses  this 
criteria. 

The  aaxJiite.on. target  specifies  the  maximum  number  of  shots  hit  on  the  target  before  the 
target  wfll  be  considered  not  a  threat  (or  undefeatable). 

The  target.prloritiea  parameter  contains  the  prioritized  list  of  vehicle  classes.  Enemy  vehi¬ 
cles  wfll  be  compared  to  this  list  to  determine  the  priority  of  the  enemy  vehicle.  If  an  enemy  does 
not  match  any  class  in  the  list  then  it  will  be  given  the  lowest  priority.  The  highest  priority  is  10 
and  the  lowest  is  1. 

When  a  SILVAsseu  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the 
task  data  structure  are  rrferenced  to  customize  the  task’s  behavior.  Since  libvassess  implements  a 
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vehicle  level  task,  these  parameters  are  typically  initialized  and  modified  by  unit  tasks  which  are 
responsible  for  directing  vehicle  level  behavior. 


The  parameters  are  represented  in  the  task  data  structure  as  follows: 


typedef  struct  vassess-paraBaters 

ObjectID  sctr.rgt.bnd; 

ObjectlD  Bctr.lft.bnd; 

f  loat64  sulx.  threat. range ; 

f loat64  SMZ. threat . aspect ; 

floated  min. threat. speed; 

floated  f ire.at.pos [2] ; 

VASSESS.ROE  peraission; 
VASSESS.FIBE,TYPE  fire. type; 

}  VASSESS.PARil(ETERS; 


sctr.rgt.bnd  specifies  the  right  sector  boundary.  Targets  within  a  sector  will  have  priority 
over  targets  outside  of  the  sector. 


■az.threat.range  specifies  the  left  sector  boundary.  Targets  within  a  sector  will  have  priority 
over  targets  outside  of  the  sector. 


■az.threat.range  specifies  the  maximum  range,  in  meters,  beyond  which  a  potential  enemy 
will  not  be  considered  a  threat. 


■ST.bhreab.aspecb  specifies  the  majdmum  aspect  an^e,  in  radians,  above  which  a  potential 
enemy  will  not  be  considered  a  threat. 


■la.threat.speed  specifies  the  minimum  target  velocity,  in  meten  per  seccmd,  below  which  a 
potential  enemy  will  not  be  considered  a  threat. 


^l^fv.ht.position  is  the  position  used  when  pezsission  is  FIRE.AT.POSITIQV. 


P***ti**i«»  specifies  whether  permission  to  fire  is  currently  enabled.  This  value  is  supplied 
as  a  paxameta  which  may  be  propi^ted  as  recommaadations  from  this  task  (see  Section  2.6 
[vass  get  recommendation],  page  9)  should  a  potential  enemy  satisfy  the  target  criterion  specified 
by  the  ■ax.threat.range,  ■ax.^breat.aspect  and  adn.threat.8peed  parameters,  peznission 
can  take  three  values: 
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•  VASSESSJHOLDJ'IRE 

•  VASSESS-FIREJIT.WILL 

•  VASSESSJIRE_POSmON 

fir«.t7p«  tpedfies  the  method  of  firing  at  the  enemy,  f  ire.type  can  be  set  to: 

•  VASSESSJ)ISTRroUTEDJIRE 

•  VASSESS.VOLLEYJFIRE 

•  VASSESSJfONE 

If  fire,  type  is  set  to  VASSESSJDISTRIBUTED  J'IRE  then  VAssess  will  try  to  choose  a  target 
that  is  not  b«ng  targeted  by  someone  else.  If  all  spotted  enemy  vehicles  are  being  targeted  by 
someone  dse  then  the  vehicle  will  target  the  highest  priority  enemy  vehicle. 

If  fire.tjpo  is  either  VASSESS.VOLLEYJ'IRE  or  VASSESS JfONE  then  VAssess  wiU  choose 
a  target  that  is  the  highest  priority.  These  two  types  do  not  check  to  see  if  the  spotted  enemy 
vdkicle  is  being  targeted  by  someone  dse 
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2  Fu  n  ction  s 


The  following  sections  describe  each  function  provided  by  libvassess,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  vassjiiit 

void  TaBs.init(data.path,  reader.flaga,  tcc) 
char  edata.path: 

ttint32  reader.flags: 

COORD.TCC_PTR  tcc; 

*data.path* 

Specifies  the  directory  where  data  files  are  expected 
‘reader.flaga* 

Specifies  the  flags  to  use  when  data  files  are  read 
*tee’  Specifies  the  local  coordinate  system 

vaaa.init  initializes  libvassess.  Call  this  before  any  other  libvassess  function. 


2.2  vazs^lassJnit 

void  vaM.cla«8.init(paz«nt.clas8) 

CLA8S.PTR  par«nt.cla88; 

‘p8r«at_cla88’ 

Class  of  the  parent  (declared  with  claas.declaze.class) 

Ta8S.ela88.ittit  creates  a  handle  for  attaching  vassess  class  information  to  vehicles.  The 
parent.claaa  will  likely  be  safobj  .class. 


2.8  vassjcreate 


void  vass.czeateCvehicle.id,  paraos,  ctdb,  db,  unit.entry) 
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int 

VASSESS.PARAHETRIC_DATA 

CTDB 

PO.DATABASE 

po.DB.ErrRy 


vehicle.id: 

^paraas: 

*ctdb; 

*db: 

*iinit_entry; 


‘vahicla.ld’ 

Specifies  the  vehicle  ID 

*paraBs’  Specifies  initial  parameter  values 

‘etdb’  Specifies  terrain  database  information 

*db*  Specifies  the  PO  database  where  the  unit  can  be  found 

*unit_«ntz7’ 

Specifies  the  unit  representing  the  vehicle  in  the  PO  database 

vass.ereate  creates  the  vassess  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


2.4  va88.jdestroy 

▼old  ▼ass.dMtxoyCTehicle.id.  i8.migration) 
ist32  ▼ohiclo.id; 
intSS  isjBigration: 

‘▼•hlelo.id* 

Specifies  the  vehicle  ID 

Specifies  that  the  destroy  is  due  to  migration 


▼asa.destroy  frees  the  vassess  class  information  for  a  vehicle.  This  should  be  called  before 
frering  the  class  user  data  with  class.free.user.data. 


2.5  vassJnitjtask jstate 


void  ▼ass.init.task.stateCtask,  state) 
TaskClass  *task; 

TaakStateClass  estate; 
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*tMk’  Spccifto  a  pointer  to  the  task  class  object  to  be  initialized. 

‘■tate*  Retoms  the  initialized  state 

Given  a  new  SILVAsaess  task  that  is  about  to  be  created,  vass_init_ta8k_state  initializes 
the  modd  size,  and  state  variables. 


2.6  vas8.,get.jecommendation 

void  vaan.get.reeoaMndation(vehicle.id,  rec) 
lnt32  vehicle.id; 

VASSESS.IIECOMNEMDATIOI  *rec; 

‘vehicle.id* 

Specifies  the  vehicle  ID 

‘zee’  Specifies  a  painter  to  return  the  recommendation  into. 

vaM.get.recoaBaadation  returns  the  current  recommendaticm  for  the  highest  threat.  The 
recommendation  has  the  fdlowing  structure: 

tTpedef  struct  vassess.reconBMndation 

< 

iat32  target; 

uiat32  mmition; 

evsiqpon; 

VASSBSS.1I0B  pezaissioa; 

>  ▼ASSESS.RBCOmiEnATIOl: 

target  is  interpreted  as  the  the  vehicle  id  of  the  highest  threat, 
auaition  is  the  recommended  munition  type  to  use  against  the  threat, 
weapon  is  the  name  d  the  weapon  to  use  against  the  treat. 

pezaisBion  specifies  the  rules  of  engagement  against  the  threat.  It  can  take  the  following 
mumerated  values: 


<VASnSS.HOLD.FIRB* 

This  specifies  not  to  shoot. 
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‘VASSESS.FIIIE.AT.WILI.’ 

This  specifies  that  permission  to  fire  is  granted. 

The  permission  is  derived  from  the  initial  permission  as  specified  in  the  task’s  parameters.  If 
the  task  parameter  for  permission  is  VASSESS_FI11E.AT.WILL,  and  if  an  available  target  satisfies 
all  constraints  specified  in  the  other  parameters,  the  recommandation  for  fire  permission  will  be 
VASSESS.FIRE.AT.WILL.  In  all  other  cases,  the  recommendation  will  be  VASSESS.HOLD.FIRE. 


2.7  vas8.get ^recommendation J'rom.public 

void  vaaa.get.reconawndatlon.from.public(db.  task,  rec) 

PO.DATABASE  «db; 

TaakClaas  etask; 

VASSESS.RECQNMEIDATZOIf  *rec; 

*db’  Specifies  the  PO  database. 

*task'  Specifies  a  SlLVAasesa  task  which  is  to  be  interpreted. 

‘rec’  Specifies  a  painter  to  return  the  reconunendation  into. 

v—».ft.reco— ndation.froa.public  returns  the  current  recommendation  for  the  high¬ 
est  threat.  The  values  returned  into  rec  are  as  in  ▼ass.get.recoBBondation  (see  Section  2.6 
[vass'get'recommendation},  page  9). 

This  function  works  on  both  locally  simulated  and  remotely  simulated  vehicles,  and  may  be 
used  by  user  interface  software  to  show  the  world  from  a  vehicle’s  point  of  view. 


2.8  va88jre8et.recommendation 

void  vass_re8et.recoaMndatlon(vehicle.id> 
lnt32  vehiclo.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

vas8.r«set.recoaBeiidation  causes  the  vassess  task  to  re-analyze  the  threat  situatation  im¬ 
mediately  on  the  next  tick.  This  is  typically  used  by  a  task  which  is  using  vassess  recommendations 
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but  discovers  a  new  situation  which  should  cause  a  new  recommendation  to  be  generated  (such  as 
destruction  of  previously  recommended  target). 
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S  A  ccets  Keys 


In  addition  to  the  functions  just  described,  libvassess  also  provides  libaccess  keys  with  which 
many  variables  can  be  fetched  at  once.  These  keys,  and  the  type  of  argument  they  expect  are  ^ven 
below: 

vassLfecominendatjon 

VASSESS.RECOMKEIfDATIOH  aarg 
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1  O  vervie w 


Libvataint  implements  a  vehicle-level  task  which  controls  the  movement  of  a  vehicle  during  an 
air-to-air  intercept.  In  its  current  implementation,  libvatiunt  guides  the  aircraft  on  a  pure-pursuit 
course  of  the  miemy.  The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated 
to  C  using  the  ‘fsa2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 

The  states  which  comprise  the  intercept  task  are  described  below. 

‘cant. iatorcopt  ’ 

Tlus  state  is  entered  when  the  aircraft  is  on  the  ground  and  cannot  perform  an  intercept. 
When  in  this  state,  the  task  continuously  checks  to  see  if  the  aircraft  has  taken  off. 
Once  the  aircraft  has  taken  off,  the  task  transitions  to  the  appropriate  state  to  begin 
the  intercept,  based  upon  the  current  intercept  geometry. 

‘•e«rch_for_tgt’ 

This  state  is  entoed  when  the  aircraft  does  not  detect  the  target  on  its  radar.  When 
in  this  state,  the  task  steers  the  mrcraft  towards  the  last  known  enemy  target  position 
and  continuously  checks  to  see  if  it  has  acquired  the  target  on  its  radar.  Once  the 
aircraft  acquires  the  target,  the  task  transitions  to  the  appropriate  state  to  be^  or 
continue  the  intercept  based  upon  the  current  intercept  geometry. 
‘anal7ze.geoMtry’ 

This  state  is  entered  when  the  target  is  first  detected  at  the  start  of  an  intercept.  This 
state  is  used  to  simulate  the  time  it  takes  for  a  pilot  in  a  real  aircraft  to  assess  the 
intercept  geometry.  When  in  this  state,  the  task  steers  the  aircraft  to  point  its  nose 
at  the  target  and  maintain  that  course  fm  a  predetermined  distance  (specified  in  the 
task  parametric  data).  After  the  aircraft  has  traveled  that  distance,  the  task  computes 
the  missiles  it  will  shoot  for  this  intme^t,  computes  the  distances  at  which  to  shoot 
those  missiles,  sdects  the  first  missile,  and  computes  the  desired  target  aspect  and  lat¬ 
eral  separation  to  achieve  an  optimal  positional  advantage  over  the  target.  Depending 
upon  the  current  intercept  gemnetry,  the  task  then  immediately  transitions  to  a  state 
in  which  it  prepares  to  take  the  first  missile  shot  (if  the  enemy  target  is  within  desired 
shot  range),  or  computes  an  initial  maneuver  which  will  put  the  aircraft  on  a  course 
to  achieve  the  desired  target  aspect  or  lateral  separation  and  transitions  to  the  ini- 
tialjmaneuver  state  to  initiate  that  maneuver  (if  the  enemy  target  is  outside  of  desired 
shot  range),  the  enemy  target  drops  off  the  aircraft’s  radar,  the  task  transitions  to 
the  searchJbrjtgt  state  in  an  attempt  to  reacquire  the  target. 

‘iaitialaNmenver’ 

This  state  is  entered  when  the  enemy  target  is  outside  of  the  aircraft’s  desired  shot 
range,  and  the  aircraft  therefore  has  time  to  make  a  maneuver  in  an  attempt  to  achieve 
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a  positional  advantage  over  the  enemy  target.  The  initial  maneuver  is  computed  based 
upon  a  series  of  rules  which  take  into  account  the  current  intercept  geometry’s  target 
aspect,  lateral  separation,  and  altitude.  When  in  this  state,  the  task  steers  the  aircraft 
in  the  direction  of  the  computed  initial  maneuver  and  continuously  checks  to  see  if 
the  desired  target  aspect  has  been  achieved  (and  if  so,  transitions  to  collisionjcourse 
state),  if  the  enemy  target  is  maneuvering  (and  if  so,  transitions  to  collisionjcourse 
state),  if  the  deisired  lateral  separation  has  been  achieved  (and  if  so,  transitions  to 
midntain_bogeyjeciprocal  state),  or  if  the  enemy  target  is  getting  close  to  the  desired 
shot  range  (and  if  so,  transitions  to  attack_heading  state).  If  the  enemy  target  drops 
off  the  aircraft’s  radar,  the  task  transitions  to  the  searchJbr  jtgt  state  in  an  attempt  to 
reacquire  the  target. 

‘■aintaiit.bogey.reciprocal’ 

This  state  is  entered  when  the  aircraft  is  performing  its  initial  maneuver  and  has 
achieved  the  desired  lateral  separation.  When  in  this  state,  the  task  steers  the  urcraft 
on  a  course  which  is  in  the  direction  opposite  the  direction  of  travel  of  the  enemy 
target  (i.e.  bog^  heading  reciprocal)  and  continuously  checks  to  see  if  the  desired 
target  aspect  has  been  achieved  (and  if  so,  transitions  to  cdlisionjcourse  state),  if 
the  enemy  target  is  maneuvering  (and  if  so,  transitions  to  collisionjcourse  state),  or 
if  the  enemy  target  is  getting  close  to  the  desired  shot  range  (and  if  so,  transitions 
to  attackJieading  state).  U  the  enemy  target  drops  off  the  aircraft’s  radar,  the  task 
transitions  to  the  searchJwjtgt  state  in  an  attempt  to  reacquire  the  target. 

‘eollisloit.conrse’ 

This  state  is  entered  whenever  the  desired  target  aspect  has  been  achieved  or  the 
enemy  target  is  maneuvering  against  the  aircraft.  When  in  this  state,  the  task  steers 
the  aircraft  on  a  collision  course  with  the  enemy  target,  and  continuously  checks  to 
see  if  the  enemy  target  is  getting  close  to  the  desired  shot  range  for  its  next  missile 
shot  (and  if  so,  transitions  to  attack  .heading  state).  If  the  enemy  target  drops  off 
the  aircraft’s  radar,  the  task  transitions  to  the  searchibrjtgt  state  in  an  attempt  to 
reacquire  the  target. 

*attack.beadiag* 

This  state  is  entered  when  the  aircraft  is  close  to  its  desired  shot  range  for  its  next 
missile  shot.  When  in  this  state,  the  task  steers  the  aircraft  on  an  attack  heading 
course  (Le.  a  course  which  is  1/3  the  target  aspect  of  pure  pursuit  of  the  target) 
and  continuously  checks  to  see  if  the  enemy  target  is  within  the  desired  shot  range  and 
within  the  selected  missile’s  launch  acceptability  r^on  (LAR)  (and  if  so,  transitions 
to  shoot  state).  If  the  enemy  target  drops  off  the  aircraft’s  radar,  the  task  transitions 
to  the  searchjbr^gt  state  in  an  attempt  to  reacquire  the  target. 

This  state  is  entered  when  the  range  to  the  enemy  target  has  reached  the  rsmge  specified 
in  the  beam  jange  task  parameter.  The  tactic  of  "turning  into  the  beam"  of  the  enemy 
aircraft’s  radar  is  used  to  defeat  the  enemy  aircraft’s  pulse  doppler  radar  modes,  which 
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cannot  track  targets  which  are  "in  the  beam".  When  in  this  state,  the  task  steers 
the  aircnJt  to  a  course  which  is  90  degrees  from  the  enemy  target’s  heading  for  a 
predetermined  length  of  time. 

‘shoot*  This  state  is  entered  when  the  aircraft  is  at  the  desired  range  to  shoot  the  currently 
selected  missile.  When  in  this  state,  the  task  requests  that  a  missile  be  fired  by  the 
vtargeter  task  (if  fire  permission  is  VATAINT_F1RE_AT-WILL).  Regardless  of  whether 
or  not  a  shot  is  taken,  the  task  then  checks  to  see  if  the  crank  task  parameter  was  set 
to  TRUE  (and  if  so,  transitions  to  the  crank  state),  or  if  the  crank  task  parameter  was 
set  to  FALSE  (and  if  so,  steers  the  aircraft  on  its  current  course  until  it  is  time  for  the 
next  shot,  time  to  bugout,  or  time  to  merge). 

‘crank’  This  state  is  entered  after  the  aircraft  has  shot  a  missile,  if  the  crank  task  parameter 
was  set  to  TRUE.  When  in  this  state,  the  task  steers  the  aircraft  on  a  course  which  is  40 
degrees  off  of  its  attack  heading  course  in  the  direction  away  from  the  enemy  target  and 
continuously  checks  to  see  if  the  enemy  target  is  approaching  the  edge  (<  15  degrees) 
of  the  radar  scan  volume  (and  if  so,  performs  an  EASY  turn  towards  the  enemy  target 
to  keep  it  ssdely  inside  the  radar  scan  volume),  if  it  is  time  to  take  another  missile  shot 
(and  if  so,  transitions  to  attackjicading  state),  if  it  is  time  to  go  to  the  merge  (and 
if  so,  transitions  to  merge  state),  or  if  it  is  time  to  bugout  (amd  if  so,  transitions  to 
bugout  state).  If  the  enemy  target  drops  off  the  aircraft’s  radar,  the  task  transitions 
to  the  searchJor^gt  state  in  an  attempt  to  reacquire  the  target. 

‘bugout’  This  state  is  entered  after  all  planned  missile  shots  have  been  taken  and  the  aircraft  is 
12  nm  from  the  enemy  target  and  does  not  have  a  radar  guided  missile  in  flight.  When 
in  this  state,  the  task  steers  the  aircraft  on  a  course  which  puts  the  enemy  target  180 
d^rees  behind  the  aircraft  and  continuously  checks  to  see  if  the  enemy  target  is  180 
d^rees  behind  the  aircraft  and  the  aircraft  has  created  a  separation  of  6  nm  from  the 
enemy  target  (and  if  so,  transitions  to  the  END  state  to  end  the  intercept). 

‘■ergo’  This  state  is  entered  when  the  range  between  the  aircraft  and  the  enemy  target  is 
less  than  12  nm,  smd  cither  the  aircraft  has  a  radar  guided  missile  in  flight  or  the 
disengagejnethod  task  parameter  was  set  to  VATAINT-MERGE.  When  in  this  state, 
the  task  steers  the  aircraft  on  a  pure  pursuit  course  and  continuously  checks  to  see  if 
the  enemy  target  is  getting  close  to  the  desired  shot  range  for  the  next  missile  to  shoot 
(and  if  so,  transitions  to  shoot  state),  or  if  the  range  to  the  enemy  target  is  less  than 
1  nm  (and  if  so,  transitions  to  the  END  state  to  end  the  intercept). 

Libvataint  depends  on  libvas.sess.  libvtargctcr,  libvtab,  libclass,  llbctdb,  libpo,  libhulls,  libcom- 
ponents,  libaccess,  libreader,  libsiatnion.  iib<'ditor,  libparmgr,  libradar,  librdreonst,  libtime,  libvec- 
mat,  libentity,  libsensors,  libsuppli<*s.  lilifrs,  liblar,  and  libtask. 
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1.1  Task  Parameters 

When  a  Slf.VATAInt  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 


tjpedef  struct  Tatalnt.paraswters 

•C 


> 


VehielelD 

uintl6 

float64 

float64 

VATAIIT.FIRE.PERMISSIOH 

iBt32 

VATAIIT.HEAPOIS.EVABLEO 

int32 

VATAIMT.DISEIGAGE.ItETHOD 

iat32 

float64 

VATAIIT.PARAIfETERS : 


target. id; 
paddingl; 

target. bearing;  /*  radians  */ 
target.range;  /*  asters  */ 
f ire.petaiss ion ; 

«eapon.count: 

ueapons.snablsd [VATAIMT.MAX. WEAPONS] 
crank; 

di8engage.Bothod ; 

padding2; 

beaB_rangs: 


‘targot.id* 

Specifies  the  id  of  the  vehicle  to  intercept. 

*target.bsariag’ 

Specifies  the  bearing  to  the  target  in  radians.  This  parameter  is  only  set  if  the  targeted 
is  not  known. 

*targst.raiige* 

Spedfies  the  range  to  the  target  in  meters.  This  parameter  is  only  set  if  the  target  Jd 
is  not  known. 

*firo.psxBissioa’ 

Specifies  the  fire  permission  (VATAINT.HOLD  J’IRE,  VATAINTJ'IREJiT.WILL)  to 
be  used  during  the  intercept. 

‘ssapon.conBt’ 

Specifies  the  number  ci  weapons  in  the  weaponsjenabled  list. 

‘voapons.oaabled* 

Specifies  the  weapons  which  the  aircraft  is  allowed  to  shoot  during  the  intercept, 
‘crank’  Specifies  whether  to  perform  a  crank  maneuver  after  each  shot  taken  during  the  inter¬ 
cept. 

*disengage.jMthod’ 

Specifies  how  the  urcraft  should  disengage  from  the  target  it  is  intercepting  if  it  does 
not  destroy  it.  This  can  take  the  values  VATAINTJNTERNAL,  VATAINT JdERGE, 
and  VATAINT.BUGOUT.  If  it  is  set  to  VATAINTJNTERNAL,  the  disengage  method 
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used  will  be  based  upon  air-to-air  intercept  tactics  taking  into  account  the  range  to  the 
target  and  whether  a  radar-guided  missile  is  in  flight.  If  it  is  set  to  VATAINT_M£RG£, 
the  aircraft  will  always  go  to  the  merge  to  disengage.  If  it  is  set  to  VATAINT_BUGOUT, 
the  aircraft  will  always  bugout  (no  later  than  12  nm  from  the  target)  to  disengage. 

*beaB_range* 

Specilies  the  range  in  meters  at  which  the  aircraft  should  turn  into  the  enemy  target’s 
radar  beam. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libvataint,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  vataintjnit 

void  vataint.inltC) 

Tataiat.inlt  initializes  libvataint.  Call  this  before  any  other  libvataint  function. 


2.2  vataint_cia88 Jnit 

▼old  ▼ataint.clasa.lnltCparent.elass) 

CLASS.PTR  parent. class; 

*paront.class* 

Class  of  the  parent  (declared  with  class.declare.class) 

▼ataiat.elass.iait  creates  a  handle  for  attaching  vataint  class  information  to  vehicles.  The 
parent. class  will  likely  be  safobj. class. 


2.3  vataint jcreate 


▼old  ▼ataint.createCvebicle.ld,  paraas,  po.db,  ctdb) 
iat32  vehicle.id; 

VATdIIT.PAlUIlETBIC.OATA  eparaos; 

P0.DATABASE  *po.db; 

CTTO  «ctdb; 


‘vehicle.id* 

Specifies  the  vehicle  ID 

‘parans*  Specifies  initial  parameter  values 

‘po.db*  Specifies  the  PO  database 
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*et<lt>’  Specifies  the  terrain  database  currently  in  use 

vataint.create  creates  the  vataiint  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  vataint_destroy 

▼old  vatalnt_destro7(Tehicle.id) 
int  vehicle. id; 

‘▼ehicle.id’ 

Specifies  the  vehicle  ID 

vatalat.deatxey  frees  the  vataint  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.f  ree.user.data. 


2.5  vataint Jnit.ta8k.3tate 


void  ▼ataint.lalt.task.atateCtaak,  state) 
TaskClass  *task; 

TaskStateClass  estate; 


*task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SILVATAIat  task  that  is  about  to  be  created,  vataint.  init.task_state  initializes 
the  model  size,  and  state  variables. 


2.6  vataint jable.toJntercept 

int32  vataint.able.to.interceptfvehicle.id,  ctdb) 
int32  vehlcle.id; 

CTDB  ectdb; 
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‘T«hicl«.ld’ 

Specified  the  Vehicle  ID. 

‘ctdb’  The  ctdb  pester  for  terrain  querries. 

Determine  if  a  vehicle  is  able  to  intercept.  If  the  air  vehicle  is  not  in  the  air,  then  it  is  not  able 
to  intercept  yet.  This  function  will  also  be  called  by  the  unit  air-to-air  intercept  task,  in  order  to 
see  if  it  needs  to  command  a  vehicle  to  take  off  before  commanding  it  to  intercept. 


2.7  vataint..{(et .target .recommendation 


void  vataint.get_tazget.recoBnendation(vehicle_id,  rec) 
int32  vehicle.id; 

VTAIIGETEILTAIIGET.RECOMNEVDATIOH  *rac: 


‘vehicle.id* 

Specified  the  Vehicle  ID. 

'rec*  The  current  target  recomendation. 


This  fuBCticm  returs  the  current  target  recomendation  that  vataint  is  using. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libvatgmdtrgt,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 

TEMPLATE:  Correct  argument  lists  and  descriptions  of  these  functions. 

2.1  vatgtgJnit 

▼old  vatgtg.inlt() 

vatgtg.init  initialises  libvatgmdtrgt.  Call  this  beftve  any  other  libvatgmdtrgt  function. 


2.2  vatgtg^Iass Jnit 

▼old  ▼atgtg.class.lnitCparent.class) 

CLASS.PTR  parent.class; 

*par«at.class’ 

Class  of  the  parent  (declared  with  class.daclare.claas) 

▼atgtg.class.inlt  creates  a  handle  for  attaching  vatgmdtrgt  class  information  to  vehicles. 
The  parent.class  will  likely  be  safobj  .class. 


2.3  vatgtg.create 


▼old  ▼atgtg.createCvehlcle.id,  paraas) 
int  ▼ehicle.id; 

VATGlUn}TRGT.PAIUIlETRZC.DATA  eparaM; 

‘▼ehicle.id’ 

Specifies  the  vehicle  ID 
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‘paraas’  Specifies  initial  parameter  values 

▼atftg.craata  creates  the  vatgmdtrgt  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  vatgtgudestroy 

void  vatgtg.dattroy(Tahicla.id) 

Int  vahicla.id; 

*vahicla.id* 

Specifies  the  vehicle  ID 

»atgtg_da8troy  frees  the  vatgmdtrgt  class  information  for  a  vehicle.  This  should  be  railed 
before  fremng  the  class  user  data  with  clasB_f ree.uaer.data. 
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1  Overview 


Libveep  implements  a  vehicle>level  task  which  performs  a  Combat  Air  Patrol  (CAP).  It  flies 
a  racetrack  pattern  looking  for  targets  to  intercept.  The  task  state  machine  is  written  using  the 
AAFSM  fonnat  which  is  translated  to  C  using  the  ‘f sB2ch*  utility  (see  section  'Overview’  in  LibTask 
Programmer’s  Manual). 

Libveap  depends  on  libpo,  libhulls,  Ubvflwrte,  libvtab,  libclass,  Ubetdb,  libaccess,  libstatmon, 
libeditor,  Ubreader,  libparmgr,  librdrconst,  libveemat,  libentity,  libcomponents,  and  libtask. 


1.1  Task  Parameters 


When  a  SILVCAP  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task  data 
structure  are  referenced.  The  parameters  are  described  by  the  following  structure: 


typedef  struct  veap.paraasters 


ObJectID 

position: 

ttintl6 

.padding 

float64 

orientation: 

float64 

length_of.legs: 

float64 

inbound.leg.speed : 

float64 

otttbotmd.leg_speod : 

float64 

altitude: 

>  VCAP.PAIUUIETERS: 


‘position’ 

A  persistoit  object  which  defines  the  locatitm  to  perform  the  CAP.  This  object  can  be 
a  pmnt  object  or  a  text  object. 

‘orientation* 

Specifies  the  orientation  of  the  racetrack  pattern.  This  is  used  to  determine  the  direc¬ 
tions  ci.  the  inbound  and  outbound  legs. 

‘length_of.legs’ 

Specifies  how  long  each  leg  of  the  track  should  be. 

‘inboiind.leg.s]>eed’ 

Specifies  the  speed  that  the  aircraft  will  be  moving  on  the  inbound  leg  of  the  track. 
‘otttboand.lsg.spaod* 

Specified  the  speed  that  the  aircraft  will  be  moving  on  the  outbound  leg  of  the  track. 
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‘altituda* 

Specifies  the  altitude  the  aircraft  will  be  flying  at. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libvcap,  including  the  format  and 
meaning  ci  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  vcapJnit 

▼old  vcap.initC) 

▼cap_lait  initializes  libvcap.  Call  this  before  any  other  libvcap  function. 


2.2  vcapuclass Jnit 

void  Tca^.elas8.ialt(parent.ela8a) 

CLASS.PTR  parant.elass; 

‘parent.elass* 

ClsM  of  the  parent  (declared  with  elass.declare.class) 

Tcap.class_iait  creates  a  handle  for  attaching  vcap  class  information  to  vehicles.  The  parant.elass 
will  likdy  be  safobj  .class. 


2.3  vcapjcreate 

▼old  ▼cap.czeatoCeehlcla.id,  parana,  po.db,  ctdb) 
iat  vahicla.id; 

VCAP.PiRAIIETRIC.DATA  eparaas; 

PO.DATABASE  *po.db; 

CTDB  *ctdb; 

‘vohicle.id’ 

Specifies  the  vehicle  ID 

'parasMt*  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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*ctdb*  Specifies  the  terrain  database  currently  in  use 

vcap.cren'te  creates  the  vcap  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block  of 
Ubclass  user  data. 


2.4  vcap.jde8troy 

▼old  Tcnp_deetroy(Yehicle.id) 
int  vehlcle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

veap_deatro7  frees  the  vcap  class  information  for  a  vehicle.  This  should  be  called  before  freeing 
the  class  user  data  with  clasa.f  ree.user.data. 


2.5  vcap Jnit.:ta8kjBtate 

void  vci9.1iiit_task_8tate(taak.  state) 

TaskClaas  atask; 

TaskStateClass  estate; 

*taak’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

^atate’  Returns  the  initialized  state 

Given  a  new  SILVCAP  task  that  is  about  to  be  created,  vcap_init_ta8k.8tate  initializes  the 
model  size,  and  state  variables. 


2.6  vcap^ble.to.jcap 


int32  vcap.able.to.capCvehicle.id,  ctdb) 
int32  vehicle.id; 

CTDB  actdb; 
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‘v«hicl«.id’ 

Specifies  the  vehicle  ID 

*etdb’  Specifies  the  ctdb  terrain  databue  to  use  for  terrain  lookups 

This  routine  determines  if  a  vehicle  is  able  to  perform  a  CAP.  If  the  air  vehicle  is  not  in  the  air, 
then  it  is  not  able  to  perform  a  CAP  yet.  This  function  will  also  be  called  by  the  unit  CAP  task,  in 
order  to  see  if  it  needs  to  command  a  vehicle  to  take  off  before  commanding  it  to  perform  a  CAP. 
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1  O  verview 


LibVCoUide  provides  a  task  which  allows  vehicles  to  recover  from  collisions  and  near-collisious. 
The  task  has  three  states: 


waiting  In  this  state,  the  software  waits  for  a  collision  to  occur  or  for  libmovemap  to  go  into 
a  state  where  it  cannot  plan  (presumably  because  it  has  fallen  into  the  configuration 
space  boundaries  of  an  obstacle). 

delay  After  detecting  the  need  to  resolve  a  collision,  the  machine  waits  in  this  state  for  a 
random  period  of  time,  prior  to  dealing  with  the  collision.  The  reason  for  this  is  two¬ 
fold:  it  simulates  the  delay  a  human  would  probably  exhibit,  and  it  prevents  deadlock 
collision  reactions  between  multiple  vehicles  by  making  the  actions  of  each  unique  with 
respect  to  all  others  (analogous  to  the  random  delays  between  ethemet  retransmissions 
after  collisions). 

resolve.coUiiion 

In  this  state,  the  machine  instructs  the  movement  arbitrator  to  move  backward  or 
forward,  left  or  right,  according  to  the  nature  of  the  collision,  and  the  surrounding 
terrain  features. 


The  format  of  the  parametric  data  is  as  follows: 


(SILVCollide  (background  C  on  I  off  1) 
(■in_dela7  <intoger  ■>>) 
(■az.delay  <integer  wb>) 
(backup.distanco  <real  ■stexs>) 

) 


background  specifies  whether  the  task  should  be  automatically  created  as  a  background  task  of 
the  vehicle  when  the  vehicle  is  created. 


■l&_delay  and  ■ax.delay  spedfy  the  range  of  delay  times  which  should  be  generated  for  the 
random  ddaying  state 


backc^.distance  specifies  the  distance  which  the  vehicle  should  travel  for  each  attempt  to 
disengage  from  the  collision. 
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1.1  Examples 


The  following  is  an  example  set  of  VCollide  parameters,  which  yields  delays  between  2  and  5 
seconds,  and  backs  up  4  meters  from  each  collision: 


(SN_ VCollide 
(background  on) 
(■in_delay  2000) 
(aaz_delay  SOOO) 
(backup.dlstance  4.0)) 
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2  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libvcollide,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  vcollideJnit 

void  vcollide.initO 

vcollida.inlt  Initializes  libvcollide.  Call  this  before  any  other  libvcollide  function. 


2.2  vcollideuciass Jnit 

void  veollide.cIaM.lnit  (parent. clasn) 

CLASS.PTR  parent. class: 

'parent.elass* 

Class  of  the  parent  (declared  with  class.declare.class) 

vcollide.class.init  creates  a  handle  for  attaching  vcollide  class  information  to  vehicles.  The 
parent.class  will  likely  be  safobj.class. 


2.3  vcollide.create 

void  vcollide.createCvehicle.id,  paraas,  db,  unit. entry,  ctdb) 
lat  v^cle.id; 

VCOUJOB.PmNETRIC.DATA  eparaw; 

P0.0ATABA8E  *db: 

P0.0B.BITRT  eunit.entry; 

CTOB  ectdb; 

*v«liicle.id’ 

Specifies  the  vehicle  ID 
‘paraas’  Specifies  initial  parameter  values 
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*db’  Specifies  the  PO  database 

‘unit.entry’ 

Specifies  the  PO  entry  of  the  unit  which  corresponds  to  this  vehicle 
*ctdb’  Specifies  the  terrain  database 

vcollide.croate  creates  the  vcoUide  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data.  If  the  paramters  so  indicate,  this  routine  will  also  create  a  task  in  the 
unit’s  background  frame. 


2.4  vcollide-destroy 

void  Tcollide.destroyCvehlcle.id,  is_migration) 
iAt32  vehicle.id; 
int32  is.migratlon: 

‘vehlcle.ld* 

Specifies  the  vehicle  ID 

*is..Bigrntioa’ 

Specifies  that  the  destroy  is  due  to  migration 

▼coUide.dMtzoy  frees  the  vctdlide  class  information  for  a  vehicle.  This  should  be  called  before 
frreeing  the  class  user  data  with  class.free_u8ar.data. 


2.5  vcollide^ollision 


void  vcollids.coUislonCvahlcle.id*  «ith.vboB) 
iBt32  vohicla.id: 

lBt32  witli.irtioai; 

‘valiicla.id* 

Specifies  the  vehicle  ID 

‘vith.vhMi’ 

Specifies  the  other  party  in  the  cdlisim 


YColllde.eollisioa  infcnnns  libvcdlide  that  a  collision  occurred,  so  that  the  task  may  react 
to  the  cdHrioa.  Colfisioas  with  the  terrain  should  be  indicated  by  a  vith.idioai  value  of  0. 
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1  Overview 


Libveemet  ie  a  vector  and  matrix  operation  library.  Most  functions  are  supported  in  many 
formats,  and  are  named  using  a  regular  convention: 

2D  or  3D  Name  starts  with  vaat2  or  vmatS 

Arguments  individually  or  in  an  array 

Next  characters  are  e.  or  just  _ 

32  bit  or  64  bit  Aoating  point 

Name  ends  with  32  or  64 

Funetum  or  macro 

Name  is  in  loeercase  or  ALL  CAPS 

For  example,  the  32  bit,  3D,  vector  add  function  which  takes  its  arguments  individually  is  called 
vMit3e.vec.add64.  Most  macro  versions  are  not  differentiated  by  bit  length,  because  the  compiler 
will  know  based  upon  the  definitions  of  the  variables  used. 

The  manual  entry  for  each  function  specifies  which  versions  are  provided.  The  prototype  ^ven 
in  the  manual  entry  uses  generic  terms  as  fallows: 

scalar  s  Either  float32  s  or  float64  s 

vector  V  One  of  the  following: 

float32  vx,  vy 
float32  vx,  vj,  vz 
float64  vx.  vy 
float64  vx,  vy.  vx 
float32  vC2] 
float32  vC3] 
float64  vC23 
float64  vC3] 

isatrix  ■  One  oi  the  following: 

flont32  aC2]C2] 
flont32  aC3] [3] 
float64  ■C23C2] 
float64  ■C33C33 

Every  fhnetion  and  macro  has  been  written  such  that  the  same  vector  or  matrix  may  be  passed 
same  than  once.  For  example,  the  expression. 
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float64  aC3].  bC3]; 

•  •  • 

TBat3.cro>B_prod64(a,  b,  a): 

is  perfectly  legal.  However,  the  routines  which  take  a  combination  of  vectors  and  matrices  do  not 
check  for  a  resultant  vector  being  a  row  of  a  passed  matrix.  For  example,  the  expression, 

float64  a  [3].  bC3]C3]: 

«  •  • 

VBMt3.vec.mat_Bnil64(a,  b,  b[l]): 
will  not  work  as  intended. 

Note  that  the  obsolete  library,  libmatrix,  was  not  consistent  in  its  argument  passing.  Since  lib- 
veemat  is  consistent,  you  must  be  very  careful  when  converting  software  to  use  libveemat.  Specifi¬ 
cally,  the  functions  which  operate  on  scalars,  and  those  which  generate  rotation  matrices  are  very 
different. 


Chftpl«r  2:  ExamplM 


2  Examples 


Add  two  vectors,  and  normalize  the  result: 


float64  vec[3]: 

VNAT3E_VEC.A0D(1.0,  2.0,  3.0. 

10.0,  20.0.  30.0. 
vec); 

VBat3.unlt64(vec,  vec); 


